Please visit the website listed above to make sure you have the latest version!
Contents
- Instructions for building the sample app.
- Overview of the Gray Council PowerPlant adapter classes.
- Instructions for using the PowerPlant adapter classes.
Instructions for building the Gray Council PowerPlant sample/test application.
Note that the 68K PowerPlant application is provided already built.
1. Open the .π file of choice (68K or PowerPC) with CodeWarrior.
2. Select the Run command to compile, link, and launch the application.
Overview of the Gray Council PowerPlant adapter classes.
AGAWindowPP (ID='GCwn')
Replacement subclass of LWindow. Gives the window an AGA gray background, with the background type depending on the LWindow windAttr_Modal flag.
AGAWindowPPX (ID='GXwn')
Extended subclass of AGAWindowPP (LWindow), for use with the supplied CPPb custom pane type. Reads the background type from additional data in the pane stream instead of using the LWindow windAttr_Modal flag.
AGADialogBoxPP (ID='GCdb')
Replacement subclass of LDialogBox. Gives the window either a 'wctb' gray background or an AGA raised gray background (depending on the window procID), and knows how to replace the standard LDialogBox default button outline mechanism with the Gray Council's push button outline attribute.
AGADialogBoxPPX (ID='GXdb')
Extended subclass of AGADialogBoxPP (LDialogBox), for use with the supplied CPPb custom pane type. Reads the background type from additional data in the pane stream instead of using the window procID.
AGAPushButtonPP (ID='GCpb')
Replacement subclass of LStdButton. Implements the AGA pushbutton by instantiating a core AGAPushButton object.
Recommended dimensions: 20x64 or 20x80, or wider to fit longer title.
AGACheckBoxPP (ID='GCcb')
Replacement subclass of LStdCheckBox. Implements the AGA check box by instantiating a core AGACheckBox object. To use the "mixed-state" capability, call LStdCheckBox::SetValue(AGACheckBox::kCheckBoxMixed).
Minimum dimensions: 12xY.
AGARadioButtonPP (ID='GCrb')
Replacement subclass of LStdRadioButton. Implements the AGA radio button by instantiating a core AGARadioButton object. To use the "mixed-state" capability, call LStdRadioButton::SetValue(AGARadioButton::kRadioButtonMixed).
Minimum dimensions: 12xY.
AGAIconPushButtonPP (ID='GCip')
Replacement subclass of AGAPushButtonPP (LStdButton), acts like a regular springloaded pushbutton, but with icon button appearance. Implements the AGA icon button by instantiating a core AGAIconPushButton object. The mUserCon should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAIconPushButtonPPX (ID='GXip')
Extended subclass of AGAIconPushButtonPP (LStdButton), for use with the supplied CPPb custom pane type. Reads the icon family resource ID, frame type, and image type from additional data in the pane stream instead of using the mUserCon.
Recommended dimensions: same as for AGAIconPushButtonPP.
AGAIconCheckBoxPP (ID='GCic')
Replacement subclass of AGACheckBoxPP (LStdCheckBox), acts like a regular self-toggling check box, but with icon button appearance. Implements the AGA icon check box by instantiating a core AGAIconCheckBox object. The mUserCon should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAIconCheckBoxPPX (ID='GXic')
Extended subclass of AGAIconCheckBoxPP (LStdCheckBox), for use with the supplied CPPb custom pane type. Reads the off and on icon family resource IDs, frame type, and image type from additional data in the pane stream instead of using the mUserCon for both.
Recommended dimensions: same as for AGAIconCheckBoxPP.
AGAIconRadioButtonPP (ID='GCir')
Replacement subclass of AGARadioButtonPP (LStdRadioButton), acts like a regular radio button that can be grouped in an LRadioGroup for mutual exclusivity, but with icon button appearance. Implements the AGA icon radio button by instantiating a core AGAIconRadioButton object. The mUserCon should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAIconRadioButtonPPX (ID='GXir')
Extended subclass of AGAIconRadioButtonPP (LStdRadioButton), for use with the supplied CPPb custom pane type. Reads the off and on icon family resource IDs, frame type, and image type from additional data in the pane stream instead of using the mUserCon for both.
Recommended dimensions: same as for AGAIconRadioButtonPP.
AGAGroupBoxPP (ID='GCgb')
Replacement subclass of LGroupBox. Implements AGA primary group box by instantiating a core AGAGroupBox set for "primary" look. If the mUserCon contains the pane ID of a sibling pane, that other pane's width will be used to determine the "title gap" that is left blank for the other pane to occupy; otherwise, the LGroupBox title is used.
Recommended dimensions: n/a; fit to contain subviews. If you use a sibling pane for the title gap, you'll need to locate it at the correct location to sit in the title gap. As an example, if you use a 16xY check box for the group box title, the check box pane should be located at left+14, top-9 relative to the group box. To conform precisely to the AGA guidelines, the title's baseline should match the group box top, and there should be 3 blank pixels on each side of the title.
AGAGroupBoxPPX (ID='GXgb')
Extended subclass of AGAGroupBoxPP (LGroupBox), for use with the supplied CPPb custom pane type. Reads the primary/secondary flag and gap pane ID from additional data in the pane stream instead of using the mUserCon for the ID and assuming primary.
Recommended dimensions: same as for AGAGroupBoxPP.
AGASecondaryGroupBoxPP (ID='GCgs')
Replacement subclass of AGAGroupBoxPP (LGroupBox). Implements AGA secondary group box by instantiating a core AGAGroupBox set for "secondary" look.
Recommended dimensions: same as for AGAGroupBoxPP.
AGAScrollBarPP (ID='GCsb')
Replacement subclass of LStdControl/scrollBarProc. Implements the AGA scroll bar by instantiating a core AGAScrollBar. By default, live scrolling is on and proportional indicator is off. You can change these defaults globally via SetGrayCouncilDefault or per object via SetAttributes. For use with an LScroller, you don't create the scroll bar objects; use AGAScrollerPP (or AGAActiveScrollerPP) instead of LScroller (or LActiveScroller) and it will create the scroll bars.
Recommended dimensions: Xx16 or 16xY.
AGAScrollerPP (ID='GCsc')
Replacement subclass of LScroller. Implements the AGA scroll bars by replacing each of the normal scroll bars created by LScroller with a core AGAScrollBar set for non-live scrolling.
Recommended dimensions: whatever fits.
AGAActiveScrollerPP (ID='GCas')
Replacement subclass of LActiveScroller (actually inherits from AGAScrollerPP, but it doesn't matter). Implements the AGA scroll bars by replacing each of the normal scroll bars created by LScroller with a core AGAScrollBar set for live scrolling.
Recommended dimensions: whatever fits.
AGASliderPP (ID='GCsl')
A subclass of LControl. Implements AGA slider by instantiating a core AGASlider. If the mUserCon contains a valid STR# resource ID, the slider will be labeled/pointy, and the slider labels are read from that resource. Otherwise, the slider will be unlabeled/rectangular. The slider's range and initial value are set from the LControl settings.
Minimum dimensions: Xx17 or 17xY.
AGASliderPPX (ID='GXsl')
Extended subclass of AGASliderPP (LControl), for use with the supplied CPPb custom pane type. Reads the labels STR# resource ID from additional data in the pane stream instead of using the mUserCon, plus the labels text traits ID and slider justification setting.
Recommended dimensions: same as for AGASliderPP.
AGALittleArrowsPP (ID='GCla')
A subclass of LControl. Implements AGA little arrows by instantiating a core AGALittleArrows. If the mUserCon contains the pane ID of an LEditField pane in the same window, the little arrows will automatically increment/decrement the number in the edit field, limited by the min/max range of the little arrows LControl.
Minimum dimensions: 23x13.
AGALittleArrowsPPX (ID='GXla')
Extended subclass of AGALittleArrowsPP (LControl), for use with the supplied CPPb custom pane type. Reads the attatched numeric field pane ID from additional data in the pane stream instead of using the mUserCon.
Recommended dimensions: same as for AGALittleArrowsPP.
AGAPopupMenuPP (ID='GCpo')
Replacement subclass of LStdPopupMenu. Implements the AGA popup menu by instantiating a core AGAPopupMenu.
Recommended dimensions: 20xY. Supports variable or fixed width option; fixed width means that the view is always drawn to fill the width of the view, while variable means it shrinks to fit the actual width of the menu item data.
AGADisclosureTrianglePP (ID='GCdt')
A subclass of LControl. Implements AGA disclosure triangle by instantiating a core AGADisclosureTriangle.
Minimum dimensions: 10x10.
AGAProgressIndicatorPP (ID='GCpr')
A subclass of LControl. Implements AGA determinate and indeterminate progress indicators by instantiating a core AGAProgress indicator. The min/max/value of the LControl are used for the progress indicator. If you set min=max, you get an indeterminate indicator. Call SetValue to prod a determinate indicator. For an indeterminate indicator, either set the mUserCon to non-zero to make the indicator automatically start idling with quantized animation, or you can call AGAProgressIndicatorPP::StartAutoAnimate yourself.
Required dimensions: Xx14.
AGAWhiteBackgroundAttachmentPP (ID='GCwa')
A subclass of LAttachment. To get a white pane background against a gray window background, attach one of these to the pane. This attachment will be common for editable text views and list views, usually used with a AGABorderFrameAttachmentPP. AGAEditFieldPP, AGATextEditPP, and AGAListBoxPP automatically attach one of these for you.
AGANotchedWhiteBackgroundAttachmentPP (ID='GCnw')
Same as AGAWhiteBackgroundAttachmentPP, but avoids erasing the "notch" in the bottom right corner of the pane.
AGABorderFrameAttachmentPP (ID='GCba')
A subclass of LAttachment. To get a "3D" sunken subview frame, attach one of these to the pane. This attachment will be common for editable text views and list views, usually used with a AGAWhiteBackgroundAttachmentPP. AGAEditFieldPP, AGATextEditPP, and AGAListBoxPP automatically attach one of these for you.
AGANotchedBorderFrameAttachmentPP (ID='GCnb')
Same as AGABorderFrameAttachmentPP, but contours the frame around the "notch" in the bottom right corner of the pane.
AGAEditFieldPP (ID='GCed')
Replacement subclass of LEditField. Implements the AGA editable text field by doing the necessary erasing and framing.
Recommended dimensions: depends on text size. 20xY is suitable for Chicago 12.
AGATextEditPP (ID='GCte')
Replacement subclass of LTextEdit. Implements the AGA editable text field by automatically attaching an AGAWhiteBackgroundAttachmentPP and an AGABorderFrameAttachmentPP to the pane.
Recommended dimensions: depends on text size and content.
AGASeparatorPP (ID='GCse')
A subclass of LPane. Implements AGA separator by instantiating a core AGASeparator. The larger dimension (h/v) is the direction that the separator is drawn.
Minimum dimensions: Xx2 or 2xY.
AGACaptionPP (ID='GCca')
Replacement subclass of LCaption. Implements static text that draws disabled in "real" gray (not qd.gray erase patBic), and erases to gray on a non-white background. You can just use LCaption if you do not change the text while the window is visible, but if you update the text while the window is open, use AGACaptionPP to avoid a white hole in the window. A standard LCaption may also be problematic in a tab panel against the tab panel's different background color.
Recommended dimensions: n/a; depends on font size.
AGAListBoxPP (ID='GClb')
Replacement subclass of LListBox. Implements the AGA list box by automatically attaching an AGAWhiteBackgroundAttachmentPP and an AGABorderFrameAttachmentPP to the pane. It also replaces the standard LFocusBox with an AGAFocusBoxPP that draws an AGA-style focus frame.
Recommended dimensions: n/a; fit to contents.
AGANotchedListBoxPP (ID='GCnl')
Same as AGAListBoxPP, but uses an AGANotchedWhiteBackgroundAttachmentPP and an AGANotchedBorderFrameAttachmentPP.
AGANotchedFocusListBoxPP (ID='GCnt')
Same as AGANotchedListBoxPP, but uses an AGANotchedFocusBoxPP as well.
AGAFocusBoxPP (ID='GCfb')
Replacement subclass of LFocusBox. Implements AGA keyboard focus frame by drawing the frame with the correct color and shape. AGAListBoxPP automatically uses an AGAFocusBoxPP to replace its standard LFocusBox that is created by LListBox.
Recommended dimensions: n/a; fit to box pane.
AGANotchedFocusBoxPP (ID='GCnf')
Same as AGAFocusBoxPP, but contours the focus box around the "notch" in the bottom right corner of the pane.
AGAPanelEnclosurePP (ID='GCpe')
A subclass of LView. As described below for AGATabPanelPP, you will probably build your tab panels by creating a separate LView-based PPob view resource for each tab's contents. If a given panel has targetable panes in it, you should probably make the root view an AGAPanelEnclosurePP rather than just an LView, because AGAPanelEnclosurePP is needed to properly grab and yield the target when the panels are switched in and out. This is only needed for targetable views like editable text fields and list boxes.
AGATabPanelPP (ID='GCtp')
A subclass of LView. Implements AGA tab panels by instantiating a core AGATabPanel set for large tab format, and handling panel content switching. If the mUserCon contains a valid STR# resource ID, the number of tabs and their labels are initialized from the STR# resource; otherwise, the object is initialized with zero tabs. To assign a panel to an existing tab, call InstallPanel. To add a new panel and a new tab, call AddPanel. Panels are built from 'PPob' resources that are LView-based rather than LWindow-based.
Recommended dimensions: depends. If it's sized larger than the size of the tabs alone, the frame box will be drawn and the tab panels will be switched in and out. If it's sized not much larger than the size of the tabs alone, there will be no frame box and no panel views will be switched in and out; the tabs will be drawn and you can catch the switching to do whatever you want with some other content view.
AGATabPanelPPX (ID='GXtp')
Replacement subclass of AGATabPanel, for use with the supplied CPPb custom pane type. Reads the tab labels STR# resource ID and tab labels text traits ID from additional data in the pane stream instead of using the mUserCon for the ID and assuming large format (system font). The font size of the specified text traits determines whether the tabs are small or large format; font size greater than 10 is large, font size 10 or less is small. The AGA standard small tabs font is 10 point Geneva bold.
Recommended dimensions: same as for AGATabPanel.
AGASmallTabPanelPP (ID='GCts')
Replacement subclass of AGATabPanelPP, set for small tab format.
Recommended dimensions: same as for AGATabPanelPP.
Instructions for using the Gray Council PowerPlant adapter classes.
1. Adding the Gray Council files to your project.
Your project needs to add two Gray Council files:
- GrayCouncil.cpp (the core classes)
- GrayCouncilPP.cpp (the PowerPlant adapter classes)
Adding these files will create the needed access paths. The PowerPlant stationery should have the remaining access paths set up correctly so you don't have to change them.
The Gray Council .cpp and .h files don't rely on any particular folder hierarchy, so you can organize them however you want. (However, the provided sample app has certain relative file path assumptions, as discussed earlier.)
If you used the PowerPlant project stationery supplied with CodeWarrior 9 to create your project file, the "Panes" section is probably missing "LGroupBox.cp", so you should add it to the project. LGroupBox.cp is located in the PowerPlant "Pane Classes" folder.
2. Enabling RTTI.
There are a couple of places in the PowerPlant adapter classes where run-time type information is used. You have a choice here.
If you don't have some reason not to, you can turn on the "Enable RTTI" checkbox in the project's C/C++ Language preferences panel. This will enable the proper RTTI testing in the code.
If for some reason you can't enable RTTI, you'll get several "RTTI not enabled" warnings from the compiler. To defeat these, simply #define NO_RTTI either in a prefix file or in GrayCouncilPP.h. This will avoid the code that uses RTTI, but you'll have to mentally promise that you're using the correct types because there will be no type-checking in these two cases:
- When you use AGADialogBoxPP for a dialog, your default button (typically the OK button), which is identified by the dialog pane's mDefaultButtonID value, must be an AGAPushButtonPP object. If it's just a standard LStdButton, you will crash. You can override AGADialogBoxPP::SetDefaultButton if you need to work around this issue.
- When you use AGALittleArrowsPP, and you specify a linked edit field pane to be incremented/decremented by the little arrows, the linked pane must indeed be an LEditField or subclass or you will crash. You can override AGALittleArrowsPP::CreateAGAObject() if you need to work around this issue.
3. Initializing.
You must call InitGrayCouncilPP() after PowerPlant has initialized the toolbox but before you instantiate any Gray Council objects. You should ThrowIfOSErr_() on the result. This function call registers the PowerPlant adapter classes and then calls InitGrayCouncil. Alternatively, you can register just the classes you will be using and then call InitGrayCouncil().
4. Specifying the pane ID.
(Note: feel free to open the file MyApplication.rsrc (in the Gray Council sample PowerPlant app folder) with Constructor to see the details of the resources used for the sample app.)
For PPob view panes, you just need to set the class ID of the pane in the resource. This applies to window and dialog root view panes (for AGAWindowPP and AGADialogBoxPP), to panes inside a window, and to attachments. For most of the adapter classes, this is all you need to do; in some of the fancier classes, you will also want to set attributes at runtime. Some classes also support use of the mUserCon field to specify attributes; there are also extended versions of these classes that require use of the CPPb custom pane types (see below for details on this).
So, you simply open the pane's information window, go to the "Class ID" field and type in the new four-letter class ID value. These class IDs are noted in the detailed class descriptions above.
For example, to use an AGAPushButtonPP in a window:
- Drag an LStdButton object from the Constructor display classes window into the layout grid.
- Open the button's information window.
- Set the Class ID to GCpb.
5a. Setting the mUserCon.
The following summarizes how the "user constant" or mUserCon field of a pane in a resource specifies additional information for certain classes (zero means to ignore it). This information is also listed in the class overviews above.
AGAIconPushButtonPP::mUserCon specifies the resource ID of an icon family for the icon button.
AGAIconCheckBoxPP::mUserCon specifies the resource ID of an icon family for the icon button.
AGAIconRadioButtonPP::mUserCon specifies the resource ID of an icon family for the icon button.
AGASliderPP::mUserCon specifies the STR# resource ID of the slider labels.
AGALittleArrowsPP::mUserCon specifies the ID of an LEditField pane in the same window to be automatically linked to the arrows.
AGAGroupBoxPP::mUserCon specifies the ID of a sibling pane whose width will be used to determine the "title gap" of the group box.
AGAProgressIndicatorPP::mUserCon, for indeterminate progress indicators (min==max), if non-zero, starts the indicator idling automatically.
AGATabPanelPP::mUserCon specifies the STR# resource ID of the tab labels. You still need to call InstallPanel to assign a panel to a tab in this case. If you're not using the fUserArea to init the tabs & labels, you will probably use AddPanel instead of InstallPanel.
5b. Using the CPPb custom pane type subclasses.
Each of the classes listed above in 5a has an extended subclass (class names ending in "PPX" instead of "PP") that you can use if using the mUserCon is not sufficient, or if you're using the mUserCon for something else. The classes that do not use the mUserCon don't need any additional information, and therefore do not need an extended class or custom pane type.
To use the extended subclasses, open the file "GCCustomPaneTypes.rsrc" with Constructor. This file is located in the Gray Council :source:PowerPlant: folder. You will see the custom pane types for the extended subclasses. There are three ways to make the custom pane types available to Constructor:
- Place GCCustomPaneTypes.rsrc in the Constructor application folder; Constructor will see it when launched.
- or, Paste the custom pane types into your app's pane resource file that will be edited with Constructor.
- or, Always open GCCustomPaneTypes.rsrc while editing your app's pane resource file with Constructor.
Be aware that if you use a custom pane type (any custom pane type, not just the Gray Council ones), you will need to have it available in one of these three ways in order to edit the pane with Constructor. If you try to open a view that contains a pane whose custom pane type definition is not available, Constructor will make you delete the pane before you can edit the view.
If you look at Constructor's display classes window, with the Gray Council custom pane types available, the hierarchy will show the custom pane types nested under their standard PowerPlant superclasses. To use a custom pane, just drag it into the view as you would a standard pane type. When you open the pane's information window (command-I or return), you will see the extra information field(s) at the bottom of the window, and the class ID will already be set to the extended class ID. Set the extra information fields how you want them, and when the pane is instantiated it will read the information from the PPob stream.
6. Changing attributes at runtime.
Once you have a Gray Council pane instantiated, you will want to do something with it! For the PowerPlant replacement subclasses, you can probably just plug them in; all standard functions like LControl::SetValue and LCaption::SetDescriptor will continue to work for the replacement subclasses. The only thing you need to avoid (and you should already be avoiding this) is for LStdControl subclasses, don't set or get the control manager value directly. You can continue to use the pane Set/GetValue functions, and you'll still be OK.
For some classes, there is no PowerPlant equivalent, so you'll need to call the view's mAGAObject-> functions directly. (This is why the mAGAObject data member is made public: so you can just call though without going through an accessor.) There is really only one thing to be careful of: focusing. Because the core AGA classes are designed to be ultra lightweight, they do not store a GrafPtr. They assume that the port is set up by the caller. So you must make sure that the view is focused before you explicitly call an AGAObject function that will cause drawing. The PowerPlant adapter classes already do this by calling this->FocusDraw() where necessary.
